502 Bad Gateway: cosa significa realmente e come risolverlo

Apri il tuo sito web e invece del contenuto vedi una pagina bianca che dice 502 Bad Gateway. Sembra spaventoso, ma nella maggior parte dei casi la soluzione è semplice. Analizziamo cosa sta succedendo e come ripristinare il tuo sito.

Cosa significa realmente 502?

Quando un visitatore richiede una pagina, la richiesta passa tipicamente attraverso due livelli: un server web frontend (di solito Nginx) e un server di applicazioni backend (PHP-FPM, Apache, Node.js o altro). Nginx riceve la richiesta, la inoltra al backend e attende una risposta.

Un 502 Bad Gateway significa che Nginx ha tentato di ottenere una risposta dal backend, ma ha ricevuto qualcosa di non valido o nessuna risposta. Il backend è andato in crash, ha rifiutato la connessione o ha restituito qualcosa che Nginx non è riuscito a interpretare.

informazioni

Un concetto errato comune: 502 non significa che il tuo server sia offline. Il server stesso funziona bene: è l'applicazione dietro Nginx che sta avendo problemi.

Cause più comuni

Il servizio backend si è arrestato. Questo è il motivo principale. PHP-FPM è andato in crash, Apache si è bloccato o un processo Node.js è terminato silenziosamente. Nginx non ha nulla con cui comunicare.

Il server esaurisce la RAM. Quando la memoria scarseggia, Linux può terminare automaticamente i processi che consumano molte risorse. Questo meccanismo è chiamato OOM killer e PHP-FPM o MySQL sono solitamente le sue prime vittime. Se ciò accade regolarmente, considera l'aggiunta di un file di swap come rete di sicurezza.

Il pool di worker di PHP-FPM è esaurito. Se il tuo sito riceve più richieste simultanee di quante PHP-FPM possa gestire, le nuove richieste vengono messe in coda e alla fine scade il tempo. Ciò accade spesso quando i bot dei motori di ricerca scansionano il tuo sito in modo troppo aggressivo; ne abbiamo parlato nella nostra guida al blocco dei bot.

Socket o porta non configurati correttamente. Nginx si aspetta di trovare PHP-FPM su un socket Unix o una porta TCP specifici. Se il percorso nella configurazione di Nginx non corrisponde alla configurazione di PHP-FPM, vedrai errori 502 subito dopo qualsiasi modifica.

Come diagnosticarlo

Per eseguire i passaggi seguenti, connettiti al tuo server tramite SSH. Puoi imparare come farlo nel nostro articolo SSH.

Passaggio 1. Verifica che il backend sia in esecuzione

Controlla lo stato del tuo servizio backend:

sudo systemctl status php8.2-fpm

Sostituisci php8.2-fpm con la tua effettiva versione di PHP o il nome del servizio backend. Se l'output dice inactive (dead) o failed, quello è il tuo problema. Riavvia:

sudo systemctl restart php8.2-fpm

Quindi controlla nuovamente lo stato per assicurarti che sia stato avviato correttamente.

Passaggio 2. Controlla il log degli errori di Nginx

Il log degli errori quasi sempre ti dice esattamente cosa è andato storto:

sudo tail -30 /var/log/nginx/error.log

Se stai usando FASTPANEL®, puoi anche visualizzare i log direttamente nell'interfaccia web: apri la scheda del sito, vai alla sezione "Log" e controlla la scheda "Frontend Error Log".

Ecco i messaggi di errore più comuni e cosa significano:

connect() failed - Connection refused - il servizio backend non è in esecuzione. Riavvia come mostrato nel Passaggio 1.

connect() failed - No such file or directory - Nginx sta tentando di raggiungere un socket Unix che non esiste. Verifica che il percorso del socket nella tua configurazione di Nginx corrisponda a quello che PHP-FPM crea effettivamente.

upstream sent too big header - il backend ha restituito intestazioni HTTP troppo grandi per il buffer predefinito. Aggiungi queste righe alla configurazione del tuo sito Nginx all'interno del blocco server:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Dopo aver modificato, testa la configurazione e ricarica Nginx:

sudo nginx -t && sudo systemctl reload nginx

Passaggio 3. Controlla le risorse del server

free -h

Se la colonna available mostra meno di 100-200 MB di memoria libera, è probabile che il tuo server stia esaurendo la RAM. Controlla cosa la sta consumando:

ps aux --sort=-%mem | head -10

warning

Se la pressione sulla memoria è la causa principale, la soluzione temporanea più rapida è aggiungere un file di swap. Tuttavia, lo swap su disco è molto più lento della RAM e non dovrebbe essere considerato una soluzione permanente. Se il tuo server esaurisce regolarmente la memoria, è ora di ottimizzare le tue applicazioni o di passare a un piano con più RAM.

Conclusione

Un 502 Bad Gateway è quasi sempre un problema del backend: un servizio in crash, worker esauriti o memoria insufficiente. Controlla lo stato del backend, leggi il log degli errori di Nginx e analizza l'utilizzo delle tue risorse. Nella stragrande maggioranza dei casi, troverai la risposta in pochi minuti.

Se preferisci non affrontare il problema da solo, su kodu.cloud forniamo supporto tecnico gratuito 24/7 con ogni VPS e server dedicato. Tutti i nostri clienti ottengono anche FASTPANEL® Extended senza costi aggiuntivi, il che rende l'analisi dei log e la gestione dei servizi significativamente più semplici tramite un'interfaccia web.